8.3 Deadlines and scheduling

A timestamp may be preceded by special keywords to facilitate planning:

DEADLINE

Meaning: the task (most likely a TODO item, though not necessarily) is supposed to be finished on that date.

On the deadline date, the task will be listed in the agenda. In addition, the agenda for today will carry a warning about the approaching or missed deadline, starting org-deadline-warning-days before the due date, and continuing until the entry is marked DONE. An example:

*** TODO write article about the Earth for the Guide
    DEADLINE: <2004-02-29 Sun>
    The editor in charge is [[bbdb:Ford Prefect]]

You can specify a different lead time for warnings for a specific deadlines using the following syntax. Here is an example with a warning period of 5 days DEADLINE: <2004-02-29 Sun -5d>. This warning is deactivated if the task get scheduled and you set org-agenda-skip-deadline-prewarning-if-scheduled to t.

SCHEDULED

Meaning: you are planning to start working on that task on the given date.

The headline will be listed under the given date⁷³. In addition, a reminder that the scheduled date has passed will be present in the compilation for today, until the entry is marked DONE, i.e., the task will automatically be forwarded until completed.

*** TODO Call Trillian for a date on New Years Eve.
    SCHEDULED: <2004-12-25 Sat>

If you want to delay the display of this task in the agenda, use SCHEDULED: <2004-12-25 Sat -2d>: the task is still scheduled on the 25th but will appear two days later. In case the task contains a repeater, the delay is considered to affect all occurrences; if you want the delay to only affect the first scheduled occurrence of the task, use --2d instead. See org-scheduled-delay-days and org-agenda-skip-scheduled-delay-if-deadline for details on how to control this globally or per agenda.

Important: Scheduling an item in Org mode should not be understood in the same way that we understand scheduling a meeting. Setting a date for a meeting is just a simple appointment, you should mark this entry with a simple plain timestamp, to get this item shown on the date where it applies. This is a frequent misunderstanding by Org users. In Org mode, scheduling means setting a date when you want to start working on an action item.

You may use timestamps with repeaters in scheduling and deadline entries. Org mode will issue early and late warnings based on the assumption that the timestamp represents the nearest instance of the repeater. However, the use of diary sexp entries like <%%(diary-float t 42)> in scheduling and deadline timestamps is limited. Org mode does not know enough about the internals of each sexp function to issue early and late warnings. However, it will show the item on each day where the sexp entry matches.